home *** CD-ROM | disk | FTP | other *** search
/ EuroCD 3 / EuroCD 3.iso / Programming / vbcc / readme.vbcc < prev    next >
Text File  |  1998-06-24  |  19KB  |  640 lines
  1.  
  2.  
  3. vbcc - portable ANSI C compiler (c) in 1995-97 by Volker Barthelmann
  4.  
  5.  
  6. INTRODUCTION
  7.  
  8.     vbcc is a free portable and retargetable ANSI C compiler.
  9.  
  10.     This archive contains the compiler, preprocessor, assembler, linker,
  11.     frontend, message browser, startup codes, C-libraries, amiga.lib
  12.     replacements as well as several other tools (mostly with complete
  13.     source) for 68k as well as PPC.
  14.  
  15.     This gives you a complete system that allows to develop programs in
  16.     ANSI C as well as Amiga-specific programs (provided you obtain the
  17.     OS-includes) running on 68k or PowerUp-boards.
  18.  
  19.     All major parts of this distribution (including compiler, preprocessor,
  20.     libraries etc.) have been compiled/assembled with this system and
  21.     apart from the OS-includes everything is included to rebuilt vbcc,
  22.     the libraries and many of the other programs.
  23.  
  24.     Note that the programs in this archive all run on the 68k even when
  25.     generating PPC-code. There is another archive which contains compilers
  26.     that run on the PPC.
  27.  
  28.  
  29. FEATURES
  30.  
  31.     vbcc..
  32.  
  33.     - comes with source
  34.  
  35.     - is free
  36.  
  37.     - is portable and retargetable
  38.  
  39.     - comes with a global optimizer that can e.g. do global common
  40.       subexpression elimination, constant propagation, function inlining
  41.       and several other optimizations (but is not yet finished and may
  42.       have some bugs)
  43.  
  44.     - should be ANSI compliant
  45.  
  46.     - can generate code that runs on a plain 68000 CPU
  47.  
  48.     - can generate code optimized for 020/030, 040 or 060
  49.  
  50.     - can generate code that uses the 68881/2, 68040/060 FPUs directly
  51.       and comes with appropriate math-libraries
  52.  
  53.     - can generate code that runs on PowerUp-boards
  54.  
  55.     - generates standard Amiga-68k-objects or PPC-ELF-objects
  56.  
  57.     - does not need too much memory
  58.  
  59.     - comes with a message browser
  60.  
  61.     - comes with a config program
  62.  
  63.     - offers a lot of error/warning messages that can be turned on/off
  64.       separately
  65.  
  66.  
  67. REQUIREMENTS
  68.  
  69.     To use vbcc you need:
  70.  
  71.     - an Amiga with OS 2.0 or higher
  72.  
  73.     - enough RAM (it is possible to translate small programs with 1MB, but
  74.       for larger programs much more will be needed)
  75.  
  76.     Stuff that is not needed, but may be very useful:
  77.  
  78.     - harddisk
  79.  
  80.     - editor
  81.  
  82.     - make, touch etc.
  83.  
  84.     - the Amiga OS-includes (they can be found on certain CDs)
  85.  
  86.     - pipe-command (to use the message browser)
  87.  
  88.     Also you should know how to use the shell and you should know ANSI C
  89.     (if you need a book I recommend (like everyone) "The C Programming
  90.     Language, Second Edition, ANSI C" by Kernighan and Ritchie).
  91.  
  92.  
  93. LEGAL
  94.  
  95.     Note that this distribution contains several programs, libraries etc.
  96.     that are from different authors and are under different legal status.
  97.     So always read the corresponding doc/guide-file to find out under
  98.     what conditions a certain file may be used, distributed etc.
  99.  
  100.     For the most part you can assume that you may use everything for
  101.     non-commercial purposes and may distribute the unchanged archive
  102.     in whole.
  103.  
  104.     Changing any parts from this archive, distributing parts of it or
  105.     using it commercially might be legal for certain parts, but illegal
  106.     for others, so read all docs carefully before doing any of the above.
  107.  
  108.     This archive contains code written by (this list may be incomplete):
  109.  
  110.     Volker Barthelmann, Frank Wille, Thorsten Schaaps, Dennis Ritchie,
  111.     Matthias Fleischer, Gunther Nikl, Mike Schwartz, Kasper Graversen,
  112.     Johnny Tevessen
  113.  
  114.     However, if you have any comments/problems etc. with anything, please
  115.     do not bother them, but write to me (volker@vb.franken.de) first.
  116.     Exceptions are the parts by Kasper Graversen.
  117.  
  118.  
  119. INSTALLATION/TUTORIAL
  120.  
  121.     [Names of directories, binaries or assigns have changed since earlier
  122.      versions as have config-files. So users of earlier versions should
  123.      read this again and do a complete re-install to avoid problems.]
  124.  
  125.     The first step (which you probably already did) is to extract the
  126.     entire archive (take care to preserve the file attributes).
  127.  
  128.     The distributed programs are for the most part only usable from a shell.
  129.  
  130.     To use vbcc the following steps are necessary:
  131.  
  132.     1. Assign vbccm68k: to the subdirectory vbcc/machines/amiga68k,
  133.               vbccppc:  to the subdirectory vbcc/machines/amigappc and
  134.               vbcc: to vbccm68k:
  135.  
  136.     2. Assign vlibm68k: to vbccm68k:lib and
  137.               vlibppc:  to vbccppc:lib.
  138.  
  139.     3. Assign vincludem68k: to vbccm68k:include and
  140.               vincludeppc:  to vbccppc:include.
  141.  
  142.        If you have the OS-includes you can either add the path to this
  143.        assign, e.g.
  144.  
  145.         assign vincludem68k: vbccm68k:include myhd:os-includes
  146.         assign vincludeppc:  vbccppc:include  myhd:os-includes
  147.  
  148.        or you can modify the vc.config (see below).
  149.  
  150.        If you want to use ixemul.lib assign ixinclude: to the directory
  151.        containing the ixemul-includes.
  152.  
  153.     4. Add vbccm68k://bin, vbccm68k:bin and vbccppc:bin to your path.
  154.  
  155.     5. set the stack to a reasonable value (perhaps some 10k).
  156.  
  157.     If you use vbcc frequently it is probably a good idea to add those
  158.     commands to your user-startup, shell-startup or similar.
  159.     However if you just want to try it out the sample script init_vbcc in
  160.     the subdirectory machines/amiga68k does all this for you.
  161.     You have to cd in its directory and start it from there, e.g.:
  162.  
  163.         cd myhd:vbcc/machines/amiga68k
  164.         init_vbcc
  165.  
  166.     Now you should be able to use vbcc. E.g. if you want to compile and
  167.     link the program hello.c you can type
  168.  
  169.         vc hello.c
  170.  
  171.     This will compile and link the file hello.c and create the executable
  172.     a.out in the current directory.
  173.  
  174.         vc hello.c -o hello
  175.  
  176.     will do the same, but the created executable will be called hello.
  177.  
  178.         vc -c t1.c t2.c
  179.  
  180.     will compile t1.c and t2.c without linking, creating the object files
  181.     t1.o and t2.o.
  182.  
  183.         vc t1.o t2.o -o tt
  184.  
  185.     will link them together and create the executable tt.
  186.  
  187.     If your program uses floating point add -lmieee to the commandline
  188.     to link with the math-library, e.g.:
  189.  
  190.         vc calc.c -o calc -lmieee
  191.  
  192.     There is also an extra.lib which includes a few functions that are
  193.     no standard ANSI functions but some people seem to regard them as
  194.     standard functions. If you use one of these add -lextra to the
  195.     commandline and read:
  196.  
  197.         vbcc/machines/amiga68k/doc/extralib.doc
  198.  
  199.     For further information read the files:
  200.  
  201.         vbcc/doc/vbcc.doc
  202.         vbcc/doc/vc.doc
  203.         vbcc/doc/vbccm68k.doc
  204.         vbcc/machines/amiga68k/doc/vclib.doc
  205.  
  206.  
  207. PPC-SUPPORT
  208.  
  209.     If you want to generate PPC-code, all you have to do is to add +ppc
  210.     to your command-line.
  211.  
  212.         vc +ppc hello.c -o hello
  213.  
  214.     will create the ELF-executable called hello. To execute it, type
  215.  
  216.         ppcrun hello
  217.  
  218.     If a PPC-program expects arguments attach them:
  219.  
  220.         ppcrun hello 1 2 "test 3"
  221.  
  222.     Options specific to the 68k can of course not be used for PPC. See
  223.     doc/vbccppc.doc and machines/amigappc/doc/* for further information.
  224.  
  225.     CAUTION: Note that if you write programs using AmigaOS-functions you
  226.              have to specify -amiga-align! You might want to add it to
  227.              vbcc:ppc if you usually use AmigaOS-functions.
  228.  
  229.     Note that PPC-support should be considered beta and there is room
  230.     for many improvements.
  231.  
  232.  
  233. CONFIGURATION
  234.  
  235.     The frontend searches for a file vc.config in ENV: and vbcc: to read
  236.     preferences. The provided sample vc.config should be usable and does
  237.     not have to be changed but you can add something to suit your personal
  238.     preferences - read
  239.  
  240.         vbcc/doc/vc.doc
  241.  
  242.     to find out more.
  243.  
  244.     If you have the OS-includes and do not want to add them to the vinclude:
  245.     assign mentioned above you can also modify the vc.config file:
  246.  
  247.     Add -I<full_path> directly after the two occurences of -Ivinclude*: in
  248.     the sample vc.config, e.g.:
  249.  
  250.         -pp=vcpp -Ivincludem68k: -Imyhd:os-include -D__STDC__=1 %s %s %s
  251.         -ppv=vcpp -Ivincludem68k: -Imyhd/os-include -D__STDC__=1 %s %s %s
  252.  
  253.  
  254. MESSAGE BROWSER
  255.  
  256.     If you start the message browser with
  257.  
  258.         run vbrowse
  259.  
  260.     it will open a window with a listview gadget. If you have a pipe
  261.     command installed you can now invoke vc via tovbr, e.g.
  262.  
  263.         tovbr vc hello.c
  264.  
  265.     and any output from vc will be displayed in the window of vbrowse
  266.     rather than in the shell. It might be convenient to make an alias like
  267.  
  268.         alias vb tovbr vc
  269.  
  270.     so that invoking vb will automatically display the output in the browser.
  271.  
  272.     If there is an error/warning-message in the browser you can invoke a
  273.     configurable command by double-clicking on the message.
  274.  
  275.     Double-clicking on the quoted line will invoke GoldEd (if you have it
  276.     installed) by default, load the file that caused the error and the cursor
  277.     will be placed on this line in the default configuration. If you use
  278.     another editor or want to change this behaviour have a look at
  279.     vbcc/machines/amiga68k/doc/vbrowse.doc.
  280.  
  281.     Double-clicking on the error-line (the one below the quoted line) will
  282.     invoke the command showerr that will open the VBCCMessages.guide and
  283.     display a more detailed description of the error (if there is one in
  284.     the guide - there are not yet descriptions for all messages).
  285.  
  286.     Read vbcc/machines/amiga68k/vbrowse.doc for further information.
  287.  
  288.  
  289. CONTENTS
  290.  
  291.     This archive contains (among others) the following files and directories:
  292.  
  293.     vbcc/
  294.  
  295.             The main directory. The source files for the compiler and the
  296.             builtin preprocessor by Thorsten Schaaps are here.
  297.  
  298.     vbcc/doc/
  299.  
  300.             Host independant documentation for the compiler is in this dir.
  301.  
  302.     vbcc/doc/History
  303.  
  304.             Changes in since earlier versions of the compiler.
  305.  
  306.     vbcc/doc/vbcc.doc
  307.  
  308.             Documentation for the target-independant part of the compiler.
  309.  
  310.     vbcc/doc/errors.doc
  311.  
  312.             A list of all error/warning-messages from the compiler -
  313.             sometimes with more detailed descriptions.
  314.  
  315.     vbcc/doc/vbccm68k.doc
  316.  
  317.             Documentation for the 68k code generator.
  318.  
  319.     vbcc/doc/vbccppc.doc
  320.  
  321.             Documentation for the PPC code generator.
  322.  
  323.     vbcc/doc/vbcci386.doc
  324.  
  325.             Documentation for the i386 code generator.
  326.  
  327.     vbcc/doc/vc.doc
  328.  
  329.             Documentation for the compiler-frontend.
  330.  
  331.     vbcc/doc/vcpp.doc
  332.  
  333.             Some short comments regarding the preprocessor from the
  334.             lcc-distribution. Read the copyright-notice.
  335.  
  336.     vbcc/doc/building.doc
  337.  
  338.             Documentation on building vbcc.
  339.  
  340.     vbcc/vcpp/
  341.  
  342.             The source for the external preprocessor by Dennis Ritchie.
  343.  
  344.     vbcc/bin/
  345.  
  346.             The directory containing binaries of preprocessor, compiler and
  347.             frontend. Additional binaries may be in machines/xyz/bin/.
  348.  
  349.     vbcc/bin/vbccm68k
  350.  
  351.             The native C compiler for m68k.
  352.  
  353.     vbcc/bin/vbccppc
  354.  
  355.             The C cross-compiler for PPC. Running on m68k.
  356.  
  357.     vbcc/bin/vbccm68k_ppc
  358.  
  359.             The C cross-compiler for m68k. Running on PPC. (optional)
  360.  
  361.     vbcc/bin/vbccppc_ppc
  362.  
  363.             The native C compiler for PPC. (optional)
  364.  
  365.     vbcc/bin/vc
  366.  
  367.             The compiler-frontend.
  368.  
  369.     vbcc/bin/vcpp
  370.  
  371.             The preprocessor from the lcc-distribution (by Dennis Ritchie).
  372.  
  373.     vbcc/machines/amiga68k/
  374.  
  375.             Everything that is specific to the Amiga68k is in this directory.
  376.  
  377.     vbcc/machines/amiga68k/doc/
  378.  
  379.             This contains documentation for the Amiga68k specific parts.
  380.  
  381.     vbcc/machines/amiga68k/doc/extralib.doc
  382.  
  383.             Documentation for extra.lib.
  384.  
  385.     vbcc/machines/amiga68k/doc/PhxAss.guide
  386.  
  387.             Documentation for the assembler by Frank Wille.
  388.  
  389.     vbcc/machines/amiga68k/doc/PhxLnk.guide
  390.  
  391.             Documentation for the linker by Frank Wille.
  392.  
  393.     vbcc/machines/amiga68k/doc/VBCCMessages.guide
  394.  
  395.             The vbcc/doc/errors.doc in Amigaguide-format (done by Walter
  396.             Doerwald).
  397.  
  398.     vbcc/machines/amiga68k/doc/vclib.doc
  399.  
  400.             Documentation for the Amiga-C-library.
  401.  
  402.     vbcc/machines/amiga68k/doc/ixemul.doc
  403.  
  404.             Documentation on using the ixemul.library.
  405.  
  406.     vbcc/machines/amiga68k/doc/vbrowse.doc
  407.  
  408.             Documentation on the message browser and several connected tools.
  409.  
  410.     vbcc/machines/amiga68k/doc/fd2lib.doc
  411.  
  412.             Documentation for fd2lib.
  413.  
  414.     vbcc/machines/amiga68k/doc/minstart.doc
  415.  
  416.             Documentation for minstart.o.
  417.  
  418.     vbcc/machines/amiga68k/doc/alib.doc
  419.  
  420.             Documentation for alib by Mike Schwartz.
  421.  
  422.     vbcc/machines/amiga68k/init_vbcc
  423.  
  424.             A sample script to do the necessary assigns etc. to use vbcc.
  425.  
  426.     vbcc/machines/amiga68k/include
  427.  
  428.             This directory contains the standard-ANSI-includes for vc.lib.
  429.  
  430.     vbcc/machines/amiga68k/bin/
  431.  
  432.             This directory contains all Amiga-specific executables.
  433.  
  434.     vbcc/machines/amiga68k/bin/PhxAss
  435.  
  436.             The assembler by Frank Wille.
  437.  
  438.     vbcc/machines/amiga68k/bin/PhxLnk
  439.  
  440.             The linker by Frank Wille.
  441.  
  442.     vbcc/machines/amiga68k/bin/vbrowse
  443.     vbcc/machines/amiga68k/bin/vsend
  444.     vbcc/machines/amiga68k/bin/tovbr
  445.     vbcc/machines/amiga68k/bin/showerr
  446.  
  447.             The message browser and some tools.
  448.  
  449.     vbcc/machines/amiga68k/bin/vconfig
  450.  
  451.             A user interface to edit the vc.config.
  452.  
  453.     vbcc/machines/amiga68k/bin/fd2lib
  454.  
  455.             fd2lib generates stubs for shared libraries and must be used to
  456.             rebuilt amiga.lib or if you want to use any custom shared-library.
  457.  
  458.     vbcc/machines/amiga68k/bin/alib
  459.  
  460.             Used to create link-libraries.
  461.  
  462.     vbcc/machines/amiga68k/lib/
  463.  
  464.             This directory contains the link-libraries and startup-codes.
  465.  
  466.     vbcc/machines/amiga68k/lib/startup.o
  467.  
  468.             The standard startup-code for vc.lib.
  469.  
  470.     vbcc/machines/amiga68k/lib/vc.lib
  471.  
  472.             The standard C-library.
  473.  
  474.     vbcc/machines/amiga68k/lib/vcs.lib
  475.  
  476.             The small data C-library.
  477.  
  478.     vbcc/machines/amiga68k/lib/mieee.lib
  479.  
  480.             Math-library that uses the MathIeee-libraries.
  481.  
  482.     vbcc/machines/amiga68k/lib/m881.lib
  483.  
  484.             Math-library that uses FPU-instructions of the 68881/2.
  485.  
  486.     vbcc/machines/amiga68k/lib/m040.lib
  487.  
  488.             Math-library that uses FPU-instructions that do not have to be
  489.             emulated on a 68040 and the Motorola emulation routines
  490.             otherwise.
  491.  
  492.     vbcc/machines/amiga68k/lib/m040o.lib
  493.  
  494.             Math-library that uses FPU-instructions that do not have to be
  495.             emulated on a 68040 and the MathIeee*.library functions
  496.             otherwise.
  497.  
  498.     vbcc/machines/amiga68k/lib/crt0.o
  499.  
  500.             Startup-code for using ixemul.library with large data model.
  501.  
  502.     vbcc/machines/amiga68k/lib/bcrt0.o
  503.  
  504.             Startup-code for using ixemul.library with small data model.
  505.  
  506.     vbcc/machines/amiga68k/lib/ixemul.lib
  507.  
  508.             Stub library for using ixemul.library with large data model.
  509.  
  510.     vbcc/machines/amiga68k/lib/ixemuls.lib
  511.  
  512.             Stub library for using ixemul.library with small data model.
  513.  
  514.     vbcc/machines/amiga68k/lib/amiga.lib
  515.  
  516.             Replacement for the standard amiga.lib.
  517.  
  518.     vbcc/machines/amiga68k/lib/amigas.lib
  519.  
  520.             Small data replacement for the standard amiga.lib.
  521.  
  522.     vbcc/machines/amiga68k/lib/minstart.o
  523.  
  524.             Small startup-code for small programs that do not use functions
  525.             from the C-library.
  526.  
  527.     vbcc/machines/amiga68k/lib/extra.lib
  528.  
  529.             Very small library containing a few functions some people want.
  530.  
  531.     vbcc/machines/amiga68k/lib/extras.lib
  532.  
  533.             Small data version of the above.
  534.  
  535.     vbcc/machines/amigappc/
  536.  
  537.             Everything that is specific to the AmigaPPC is in this directory.
  538.  
  539.     vbcc/machines/amigappc/doc/
  540.  
  541.             This contains documentation for the AmigaPPC specific parts.
  542.  
  543.     vbcc/machines/amigppc/doc/extralib.doc
  544.  
  545.             Documentation for libextra.a.
  546.  
  547.     vbcc/machines/amigappc/doc/pasm.doc
  548.  
  549.             Documentation for the assembler by Frank Wille.
  550.  
  551.     vbcc/machines/amigappc/doc/vclib.doc
  552.  
  553.             Documentation for the Amiga-C-library for PPC.
  554.  
  555.     vbcc/machines/amigappc/doc/fd2libPPC.doc
  556.  
  557.             Documentation for fd2libPPC.
  558.  
  559.     vbcc/machines/amigappc/include
  560.  
  561.             This directory contains the standard-ANSI-includes for libvc.a.
  562.  
  563.     vbcc/machines/amigappc/bin/
  564.  
  565.             This directory contains AmigaPPC-specific executables.
  566.  
  567.     vbcc/machines/amigappc/bin/pasm
  568.  
  569.             The assembler by Frank Wille running on 68k.
  570.  
  571.     vbcc/machines/amigappc/bin/pasm_ppc
  572.  
  573.             The assembler by Frank Wille running on PPC. (optional)
  574.  
  575.     vbcc/machines/amigappc/bin/ppcrun
  576.  
  577.             Program used to start PPC-ELF-executables.
  578.  
  579.     vbcc/machines/amigappc/bin/fd2libPPC
  580.  
  581.             fd2lib generates stubs for shared libraries and must be used to
  582.             rebuilt libvc.a or if you want to use any custom shared-library.
  583.  
  584.     vbcc/machines/amigappc/bin/ppc-amigaos-ld
  585.  
  586.             The GNU linker for ELF-objects. See doc/COPYING.
  587.  
  588.     vbcc/machines/amigappc/bin/ppc-amigaos-ar
  589.  
  590.             The GNU archiver for ELF-objects. See doc/COPYING.
  591.  
  592.     vbcc/machines/amigappc/lib/
  593.  
  594.             This directory contains the link-libraries and startup-codes.
  595.  
  596.     vbcc/machines/amigappc/lib/startup.o
  597.  
  598.             The standard startup-code for libvc.a.
  599.  
  600.     vbcc/machines/amigappc/lib/libvc.a
  601.  
  602.             The standard C-library. See doc/vclib.doc.
  603.  
  604.     vbcc/machines/amigappc/lib/libm.a
  605.  
  606.             Math-library. See doc/vclib.doc.
  607.  
  608.     vbcc/machines/amigappc/lib/libamiga.a
  609.  
  610.             Replacement for the standard amiga.lib.
  611.  
  612.     vbcc/machines/amigappc/lib/libextra.a
  613.  
  614.             Very small library containing a few functions some people want.
  615.  
  616.  
  617.  
  618.  
  619. BUGREPORTS/COMMENTS
  620.  
  621.     If you think vbcc generates bad code, throws enforcer hits, crashes,
  622.     seems to be not ANSI-compliant etc. and the problem is not mentioned
  623.     anywhere in this docs as known problem, please send a mail with your
  624.     system configuration, the vbcc version, the command line you used, the
  625.     source that caused the problem and a brief description of the problem to
  626.  
  627.         volker@vb.franken.de
  628.  
  629.     Also if you find problems with the includes, the libraries or you have
  630.     suggestions, dislikes etc. send me a mail.
  631.     Corrections, improvements etc. of the manuals are appreciated, too.
  632.  
  633.  
  634.  
  635. Volker Barthelmann                                      volker@vb.franken.de
  636. Kennedy-Ring 39
  637. 91301 Forchheim
  638. Germany
  639.  
  640.